Index: docs/P3-UseCaseModel/UseCase0004.md
===================================================================
--- docs/P3-UseCaseModel/UseCase0004.md	(revision b715712c7d5d3ee27c932a8a9d8e0a2bc6e85127)
+++ docs/P3-UseCaseModel/UseCase0004.md	(revision 9e6d8a2e95a15f67178a3f9b0a89aafa9a1d7f59)
@@ -37,13 +37,18 @@
    BEGIN;
 
+   -- (a) record intent — no trade has happened yet.
    INSERT INTO project.orders
-       (user_id, market_id, side, type, status, quantity, price, executed_at)
+       (user_id, market_id, side, type, status, quantity, price)
    VALUES
-       ($user_id, $market_id, 'buy', 'market', 'executed', $qty, $price, now())
+       ($user_id, $market_id, 'buy', 'market', 'open', $qty, $price)
    RETURNING id;  -- captured as $order_id
 
+   -- (b) lock and check the user balance
    SELECT available_balance FROM project.users WHERE id = $user_id FOR UPDATE;
    -- abort if available_balance < notional
 
+   -- (c) move cash from available to invested. A buy never reserves crypto
+   --     the way a sell does — it only ever adds to the position, so there
+   --     is nothing on the holdings side to commit before settling.
    UPDATE project.users
       SET available_balance = available_balance - $notional,
@@ -52,5 +57,5 @@
     WHERE id = $user_id;
 
-   -- Upsert holding with running weighted-average price:
+   -- (d) upsert holding with running weighted-average price:
    SELECT quantity, avg_price
      FROM project.holdings
@@ -61,4 +66,5 @@
    -- new_avg = (old_qty*old_avg + $qty*$price) / (old_qty + $qty)
 
+   -- (e) ledger entry
    INSERT INTO project.transactions
        (user_id, type, amount, currency, related_order, description)
@@ -66,8 +72,14 @@
        ($user_id, 'buy', -$notional, 'USD', $order_id, 'Market buy ...');
 
+   -- (f) record the resulting market trade
    INSERT INTO project.market_trades
        (market_id, executed_at, price, quantity, side, source)
    VALUES
        ($market_id, now(), $price, $qty, 'buy', 'user');
+
+   -- (g) settle the order itself — it has now actually been filled.
+   UPDATE project.orders
+      SET status = 'executed', executed_at = now()
+    WHERE id = $order_id;
 
    COMMIT;