[Docs] Formalize escrow state-machine invariants

[Jayrodri088]

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

PR must include:

• Closes #26 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 escrow settlement flow currently has multiple areas where the intended semantics are not yet fully specified in docs:

• what amount in record_payment represents
• how EscrowStatus::Settled should relate to tokenization finalization
• how EscrowStatus::Refunded impacts invoice tokens (burn/unlock/lock)

Additionally, we already detected a stuck-funds edge case on underpayment (Issue 7), but the overall state-machine invariants still need formalization.

Proposed change

Create a state-machine invariants document for escrow + token:

• define valid transitions among Created -> Funded -> Settled and Funded -> Refunded
• define invariants on token balances and escrow fields at each transition
• specify exactly when invoice tokens should be minted/burned/unlocked (once implemented)

Acceptance criteria

• Add docs/state-machine.md (or similarly named file)
• Document transition rules and invariants in a way a contributor can write tests from it
• Link to this doc from docs/lifecycle.md (Issue 23)
• Explicitly call out the chosen policy for partial/underpayment and link to Issue 7

Dependencies

• Relates to: Issue 7 (partial settlement stuck funds) and Issue 24/25 (settlement money flow)
• Requires the lifecycle doc (Issue 23) as starting context

[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.