Charge real freight in network.py/whatif.py; drop "ROI/day %" terminology

network.py: tools/network.py now computes freight cost from the real fuel
model (puga.shipping.round_trip_cost) for direct-jump transfers instead of
the flat 9250 AIC placeholder; gateway transfers or an explicit trip_cost
in the chain YAML still use that as a fallback. puga/network.py's combine()
docstring now flags that its "flows cancel, only freight matters" claim
only holds under a symmetric-price basis (uni30, the default) - under
--basis real it understates the benefit of physical transfer by the
bid-ask spread on the moved quantity.

whatif.py: now charges marginal freight too - only the EXTRA round trips
an addition needs beyond the base's existing traffic, so a small addition
riding along on already-necessary hauls costs ~0, while one that adds
meaningfully to shipped tonnage doesn't get a free pass.

Terminology: "profit/day ÷ capex" was being reported as "ROI/day X%",
which invites reading it as a compoundable rate. It's just 1/payback_days -
there's no reinvestment mechanism and every opportunity here is
capacity/market-limited, so it can't be annualized like a real yield.
Payback in days is now the primary number everywhere (scan.py, simulate.py,
network.py, whatif.py); see docs/decisions.md for the reasoning.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

puga/network.py

@@ -8,6 +8,15 @@ the transferred quantity (base A "sells" it, base B "buys" it, at the same price
 combined total needs only ONE correction: the real freight cost of physically moving it, which
 isn't in either base's isolated numbers. Leftover surplus (more produced than a partner needs) is
 still validly sold at market by the producing base; leftover deficit is still validly bought.
+
+CAVEAT: the "cancel out" claim only holds when the price basis prices buy and sell sides of a
+ticker identically (true for `uni30`, the default in tools/network.py). Under `--basis real`
+(or any basis with a genuine bid/ask spread), each base's own `simulate()` correctly books its
+flows at the real sell (bid/vwap) or buy (ask) price - but for the `moved` quantity, that's not
+what actually happens: it moves at no transaction price at all, not at both a real sale AND a
+real purchase. Summing the two bases' independent numbers and subtracting only freight therefore
+UNDERSTATES the true combined profit by the bid-ask spread on the moved quantity - a real gap,
+not symmetric cancellation, under any basis with a spread. Not corrected here.
 """
 from dataclasses import dataclass, field
 from . import fio
@@ -33,7 +42,9 @@ class Transfer:
     material: str
     src: str                    # producing base's name (key in the `bases` dict)
     dst: str                    # consuming base's name
-    trip_cost: float = 9250.0   # AIC per round trip; PLACEHOLDER until a real route/fuel model exists
+    trip_cost: float = 9250.0   # AIC per round trip; tools/network.py fills this from puga.shipping.round_trip_cost()
+                                # when src/dst are a direct-jump route and no explicit value is given in the chain
+                                # YAML - this default is the fallback for gateway routes/transfers without one
     cargo: float = 500.0        # t or m3 per trip