docs(architecture): document contract architecture and interaction flow

[Demilade10]

Description

Document the contract architecture and the subscriber/merchant interaction flow, including why subscribers approve the token contract directly rather than through subscribe(). This is not obvious from reading the code alone and will confuse new contributors without it.

Requirements and Context

• The original design had subscribe() call token.approve() internally, which caused persistent Unauthorized errors due to a Soroban limitation: cross-contract nested auth is unreliable
• The correct pattern - and the one currently implemented - has subscribers call approve directly on the token contract as a separate prior transaction, before calling subscribe()
• This architectural decision should be documented so contributors do not attempt to "fix" it by reintroducing nested auth
• The protocol uses flat recurring billing in v1 (not usage-metering) as a deliberate scope decision - this should be documented as intentional, not a missing feature
• Must cover the full lifecycle: create_plan -> approve -> subscribe -> charge

Suggested Execution

Branch name: docs/architecture

Files to touch:

• docs/ARCHITECTURE.md (new)
• README.md (add link to new doc)

Example commit message: docs(architecture): document contract architecture and interaction flow

Test and Commit

• docs/ARCHITECTURE.md created with a diagram or clearly ordered steps showing create_plan -> approve -> subscribe -> charge
• Explains why approve() must be called directly on the token contract as a separate prior transaction, not internally by subscribe()
• Documents the flat recurring billing model and explicitly notes usage-metering is deferred to v2
• Lists core contract functions with a one-line purpose for each
• Doc is linked from README.md
• Reviewed for accuracy against the current deployed contract behavior

Guidelines

• Assignment required before starting - comment to request assignment
• PR description must include: Closes docs(architecture): document contract architecture and interaction flow #4

Complexity

Trivial - 100 points