[Docs] Add canonical end-to-end lifecycle doc (escrow-token-distributor)

[Jayrodri088]

Complexity / points: Medium (150 points) - maintainer label: points-150-medium

PR must include:

• Closes #23 in the PR description
• Tests added or updated where behavior changes
• Docs updated if public API, lifecycle, or deploy steps change
• No unwrap() in production Soroban contract paths (project convention)
• cargo test passes locally; match CI (cargo fmt, cargo clippy -D warnings) when touching Rust

Problem

The contracts (invoice-escrow, invoice-token, payment-distributor) are present, but there is no single canonical document that explains the intended end-to-end invoice lifecycle:

• which contract calls which
• which token/currency each step uses (payment_token vs invoice-token)
• what state transitions are expected (escrow status + token lock/unlock)
• where fees are applied

As a result, contributors must infer behavior from Rust code and scattered README text, which increases misaligned implementations.

Proposed change

Add a Γò¼├┤Γö£ΓòóΓö¼├║╬ô├╢┬ú╬ô├╢├⌐╬ô├▓┬╝Γö£Γöñ╬ô├╢┬ú╬ô├«├ë╬ô├╢┬╝╬ô├▓┬ÑΓò¼├┤Γö£Γòó╬ô├▓┬Ñ╬ô├╢┬ú╬ô├╢├▒single source of truthΓò¼├┤Γö£ΓòóΓö¼├║╬ô├╢┬ú╬ô├╢├⌐╬ô├▓┬╝Γö£Γöñ╬ô├╢┬ú╬ô├«├ë╬ô├╢┬╝╬ô├▓┬Ñ^] lifecycle architecture doc under docs/.

What this doc must include

• Actors/roles (admin/platform, seller, buyer/investor/payer)
• Step-by-step flow with call sequences and parameters:
  • invoice-escrow::create_escrow
  • invoice-escrow::fund_escrow
  • invoice-escrow::record_payment
  • invoice-escrow::refund
  • how/when invoice-token is minted, locked/unlocked, transferred/burned
  • how/when payment-distributor is invoked and what it distributes
• Cross-contract wiring constraints:
  • how invoice-tokenΓò¼├┤Γö£ΓòóΓö¼├║╬ô├╢┬ú╬ô├╢├⌐╬ô├▓┬╝Γö£Γöñ╬ô├╢┬ú╬ô├«├ë╬ô├╢┬╝╬ô├▓┬Ñ╬ô├▓┬╝Γö£Γöñ╬ô├╢┬úΓö£ΓûÆ╬ô├╢┬ú╬ô├╢├⌐s minter relates to invoice-escrow
  • meaning of EscrowStatus::Created/Funded/Settled/Refunded
  • expected invariants (what balances must exist at each step)
• Events and error mapping: list major events to expect and which errors should be raised
• An explicit Γò¼├┤Γö£ΓòóΓö¼├║╬ô├╢┬ú╬ô├╢├⌐╬ô├▓┬╝Γö£Γöñ╬ô├╢┬ú╬ô├«├ë╬ô├╢┬╝╬ô├▓┬ÑΓò¼├┤Γö£Γòó╬ô├▓┬Ñ╬ô├╢┬ú╬ô├╢├▒Open Questions / AssumptionsΓò¼├┤Γö£ΓòóΓö¼├║╬ô├╢┬ú╬ô├╢├⌐╬ô├▓┬╝Γö£Γöñ╬ô├╢┬ú╬ô├«├ë╬ô├╢┬╝╬ô├▓┬Ñ^] section for undecided areas

Acceptance criteria

• Create docs/lifecycle.md (or similarly named file)
• Document all steps above clearly enough that a contributor can implement integration work without guessing
• Link this doc from docs/API.md (once it exists) and/or Readme.md

Dependencies

None (this issue unblocks later integration issues).

[Jayrodri088]

Deferred (Wave 1 scope)
Maintainers are focusing this wave on implementation: escrow, invoice-token lifecycle, settlement/payment flows, payment-distributor, tests, and security bugs — aligned with decentralized invoice factoring on Stellar (liquidity for sellers, yield for investors, on-chain escrow/settlement).

Documentation issues will be reopened or recreated in a later wave. If you already started work, comment here and we can link a follow-up issue.