Document the logical steps within ChannelManager deserialization stage 2

Add step comments to from_channel_manager_data to clarify the seven
logical phases of ChannelManager reconstruction:

1. Channel/monitor reconciliation
2. Initialize missing optional fields
3. Replay in-flight monitor updates
4. Reconstruct HTLC state from monitors
5. Reconstruct claimable payments
6. Construct the ChannelManager
7. Replay pending claims and fail HTLCs

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: joostjager

lightning/src/ln/channelmanager.rs

@@ -17815,6 +17815,12 @@ impl<
 			is_connected: false,
 		};
 
+		// Step 1: Channel/monitor reconciliation.
+		//
+		// Validate each deserialized channel against its corresponding ChannelMonitor to ensure
+		// consistency. Channels that are behind their monitors are force-closed. Channels without
+		// monitors (except those awaiting initial persistence) are rejected. Monitors without
+		// channels get force-close updates queued.
 		const MAX_ALLOC_SIZE: usize = 1024 * 64;
 		let mut failed_htlcs = Vec::new();
 		let channel_count = channels.len();
@@ -18075,14 +18081,17 @@ impl<
 			}
 		}
 
-		// Apply peer features from deserialized data
+		// Apply peer features from deserialized data.
 		for (peer_pubkey, latest_features) in peer_init_features {
 			if let Some(peer_state) = per_peer_state.get_mut(&peer_pubkey) {
 				peer_state.get_mut().unwrap().latest_features = latest_features;
 			}
 		}
 
-		// Post-deserialization processing
+		// Step 2: Initialize missing optional fields.
+		//
+		// Fields that were added in later versions may be None when reading older data.
+		// Generate fresh random values for these fields to maintain functionality.
 		let mut decode_update_add_htlcs = new_hash_map();
 		if fake_scid_rand_bytes.is_none() {
 			fake_scid_rand_bytes = Some(args.entropy_source.get_secure_random_bytes());
@@ -18110,6 +18119,8 @@ impl<
 			}
 		}
 
+		// Step 3: Replay in-flight monitor updates.
+		//
 		// We have to replay (or skip, if they were completed after we wrote the `ChannelManager`)
 		// each `ChannelMonitorUpdate` in `in_flight_monitor_updates`. After doing so, we have to
 		// check that each channel we have isn't newer than the latest `ChannelMonitorUpdate`(s) we
@@ -18336,6 +18347,8 @@ impl<
 			pending_background_events.push(new_event);
 		}
 
+		// Step 4: Reconstruct HTLC state from monitors.
+		//
 		// In LDK 0.2 and below, the `ChannelManager` would track all payments and HTLCs internally and
 		// persist that state, relying on it being up-to-date on restart. Newer versions are moving
 		// towards reducing this reliance on regular persistence of the `ChannelManager`, and instead
@@ -18740,6 +18753,10 @@ impl<
 			}
 		}
 
+		// Step 5: Reconstruct claimable payments.
+		//
+		// Combine claimable_htlcs_list with their purposes and onion fields. For very old data
+		// (pre-0.0.107) that lacks purposes, reconstruct them from legacy hop data.
 		let expanded_inbound_key = args.node_signer.get_expanded_key();
 
 		let mut claimable_payments = hash_map_with_capacity(claimable_htlcs_list.len());
@@ -19065,6 +19082,9 @@ impl<
 			}
 		}
 
+		// Step 6: Construct the ChannelManager.
+		//
+		// All data has been validated and reconciled. Build the final ChannelManager struct.
 		let best_block = BestBlock::new(best_block_hash, best_block_height);
 		let flow = OffersMessageFlow::new(
 			chain_hash,
@@ -19143,6 +19163,10 @@ impl<
 			testing_dnssec_proof_offer_resolution_override: Mutex::new(new_hash_map()),
 		};
 
+		// Step 7: Replay pending claims and fail HTLCs.
+		//
+		// Process any payment preimages stored in monitors that need to be claimed on the inbound
+		// edge. Also fail any HTLCs that were dropped during channel reconciliation.
 		let mut processed_claims: HashSet<Vec<MPPClaimHTLCSource>> = new_hash_set();
 		for (_, monitor) in args.channel_monitors.iter() {
 			for (payment_hash, (payment_preimage, payment_claims)) in monitor.get_stored_preimages()