docs(proposals): add proposal lifecycle & voting model concepts doc

[Ajibola6921]

Overview

This PR adds contracts/docs/concepts-proposal-lifecycle.md explaining the proposals contract's voting design: how a proposal is created, how votes are weighted and counted, what finalization does, expiry handling, and how a finalized proposal's execution ties back into group_treasury withdrawals.

Related Issue

Closes #472

Changes

Documentation

• [ADD] contracts/docs/concepts-proposal-lifecycle.md
  • Mermaid state diagram covering every ProposalStatus value and the function calls that cause each transition
  • Explains what determines a proposal passing or failing (vote count/threshold) — simple plurality: yes > no passes, else rejects (tie = rejection)
  • Explains the expiry path and why finalize_expired_proposal exists as distinct from normal finalization (semantic clarity, mutual exclusivity, guard condition differences)
  • Covers proposal creation parameters, voting mechanics (1-address-1-vote, no weighted voting, no quorum), and the full vote storage model
  • Step-by-step execute_withdraw flow showing treasury membership verification, balance checks, and the actual withdrawal call
  • Event reference table and group_treasury integration diagram

Verification Results

cargo test -p proposals
✅ 18/18 passed

All 18 tests passed, confirming the documentation accurately reflects the contract behavior.

Acceptance Criteria	Status
State diagram covers every ProposalStatus value and function call transitions	✅ 6-status Mermaid diagram with all transitions
Explains pass/fail rule precisely	✅ Simple plurality (yes > no), with tie/zero-vote examples
Explains expiry path and why finalize_expired_proposal is distinct	✅ Three reasons: semantic clarity, mutual exclusivity, guard condition differences
Explains how execution ties into group_treasury withdrawals	✅ Step-by-step flow + integration diagram

[drips-wave]

@Ajibola6921 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits