Wiring diagram + state-machine documentation for the four frozen/upgrade/permission edges

[P3az3]

Problem Statement

The codebase has these mutating entrypoints: initialize, donate, end_campaign, cancel_campaign, extend_deadline, release_milestone, release_milestone_multi_asset, claim_refund, freeze, unfreeze, upgrade. Each has its own auth, freeze, status, and reentrancy posture. There is no single document that maps out: "When the contract is X, who can do Y?".

Why it matters

Internal docs (in docs/events.md, code comments) cover individual entrypoints but lack a unified matrix. New contributors and security auditors have to read every function signature to reconstruct the model. A matrix-style table is the difference between 30 minutes and 3 minutes of audit time.

Expected Outcome

A new docs/state-machine.md that contains:

• A 2D table with fields: row = entrypoint; columns = "auth required", "freeze gates writes?", "status gate", "reentrancy lock acquired?", "mutates storage?", "emits events?", "events emitted".
• A state diagram (Mermaid or similar) showing all transitions.
• A freeze module documentation with the ordering invariant (freeze-before-auth).
• A "post-upgrade contract migration" checklist for upgrade events.

Acceptance Criteria

• docs/state-machine.md exists and is referenced from README.md.
• Each entrypoint row in the table is verified by at least one existing test name.
• The state diagram is valid Mermaid that renders correctly in GitHub preview.
• Inline /// doc comments on each entrypoint reference this doc.

Implementation Notes

• Place in docs/state-machine.md next to events.md and deployment.md.
• Use a markdown table — GitHub renders it nicely.
• Reference existing issue numbers for ownership.

Affected Files / Modules

• docs/state-machine.md (new)
• README.md (link)
• campaign/src/lib.rs (doc-comment cross-references)

Dependencies — None.

[ReinaMaze]

GM Maintainer, can I be assigned to this issue? I’ve reviewed the requirements and understand the scope. I’ll create docs/state-machine.md with the entrypoint matrix, Mermaid state diagram, freeze module documentation, and post-upgrade migration checklist. I’ll also link it from the README, add the required doc comment references, and verify each entrypoint against the existing tests.

ETA: 12 hours

[grantfox-oss]

🦊 GrantFox — @ReinaMaze has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #15)
2. Your PR will be reviewed by the MillestoneX maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@ReinaMaze's PR #66 was approved and merged by @P3az3.

🏆 @ReinaMaze: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (627 total points). Track your full progress on GrantFox.

👏 Great work, @ReinaMaze! Keep contributing to MillestoneX.