Adds user equity eligibility management

Implements functionality to manage user equity eligibility, allowing admins to grant and revoke access.

Adds database migration, models, CRUD operations, and API endpoints for managing user equity status.
This feature enables finer-grained control over who can convert expenses to equity contributions.
Validates a user's eligibility before allowing them to submit expenses as equity.

crud.py

@@ -949,3 +949,116 @@ async def delete_balance_assertion(assertion_id: str) -> None:
         "DELETE FROM balance_assertions WHERE id = :id",
         {"id": assertion_id},
     )
+
+
+# User Equity Status CRUD operations
+
+
+async def get_user_equity_status(user_id: str) -> Optional["UserEquityStatus"]:
+    """Get user's equity eligibility status"""
+    from .models import UserEquityStatus
+
+    row = await db.fetchone(
+        """
+        SELECT * FROM user_equity_status
+        WHERE user_id = :user_id
+        """,
+        {"user_id": user_id},
+    )
+
+    return UserEquityStatus(**row) if row else None
+
+
+async def create_or_update_user_equity_status(
+    data: "CreateUserEquityStatus", granted_by: str
+) -> "UserEquityStatus":
+    """Create or update user equity eligibility status"""
+    from datetime import datetime
+    from .models import UserEquityStatus
+
+    # Check if user already has equity status
+    existing = await get_user_equity_status(data.user_id)
+
+    if existing:
+        # Update existing record
+        await db.execute(
+            """
+            UPDATE user_equity_status
+            SET is_equity_eligible = :is_equity_eligible,
+                equity_account_name = :equity_account_name,
+                notes = :notes,
+                granted_by = :granted_by,
+                granted_at = :granted_at,
+                revoked_at = :revoked_at
+            WHERE user_id = :user_id
+            """,
+            {
+                "user_id": data.user_id,
+                "is_equity_eligible": data.is_equity_eligible,
+                "equity_account_name": data.equity_account_name,
+                "notes": data.notes,
+                "granted_by": granted_by,
+                "granted_at": datetime.now(),
+                "revoked_at": None if data.is_equity_eligible else datetime.now(),
+            },
+        )
+    else:
+        # Create new record
+        await db.execute(
+            """
+            INSERT INTO user_equity_status (
+                user_id, is_equity_eligible, equity_account_name,
+                notes, granted_by, granted_at
+            )
+            VALUES (
+                :user_id, :is_equity_eligible, :equity_account_name,
+                :notes, :granted_by, :granted_at
+            )
+            """,
+            {
+                "user_id": data.user_id,
+                "is_equity_eligible": data.is_equity_eligible,
+                "equity_account_name": data.equity_account_name,
+                "notes": data.notes,
+                "granted_by": granted_by,
+                "granted_at": datetime.now(),
+            },
+        )
+
+    # Return the created/updated record
+    result = await get_user_equity_status(data.user_id)
+    if not result:
+        raise ValueError(f"Failed to create/update equity status for user {data.user_id}")
+    return result
+
+
+async def revoke_user_equity_eligibility(user_id: str) -> Optional["UserEquityStatus"]:
+    """Revoke user's equity contribution eligibility"""
+    from datetime import datetime
+
+    await db.execute(
+        """
+        UPDATE user_equity_status
+        SET is_equity_eligible = FALSE,
+            revoked_at = :revoked_at
+        WHERE user_id = :user_id
+        """,
+        {"user_id": user_id, "revoked_at": datetime.now()},
+    )
+
+    return await get_user_equity_status(user_id)
+
+
+async def get_all_equity_eligible_users() -> list["UserEquityStatus"]:
+    """Get all equity-eligible users"""
+    from .models import UserEquityStatus
+
+    rows = await db.fetchall(
+        """
+        SELECT * FROM user_equity_status
+        WHERE is_equity_eligible = TRUE
+        ORDER BY granted_at DESC
+        """
+    )
+
+    return [UserEquityStatus(**row) for row in rows]