Quickly document OrderRecord class

uncloud/uncloud_pay/models.py

@@ -195,19 +195,8 @@ class BillRecord():
 ###
 # Orders.
 
-# /!\ BIG FAT WARNING /!\ #
-#
 # Order are assumed IMMUTABLE and used as SOURCE OF TRUST for generating
 # bills. Do **NOT** mutate then!
-#
-# Why? We need to store the state somewhere since product are mutable (e.g.
-# adding RAM to VM, changing price of 1GB of RAM, ...). An alternative could
-# have been to only store the state in bills but would have been more
-# confusing: the order is a 'contract' with the customer, were both parts
-# agree on deal => That's what we want to keep archived.
-#
-# /!\ BIG FAT WARNING /!\ #
-
 class Order(models.Model):
     uuid = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
     owner = models.ForeignKey(get_user_model(),
@@ -247,6 +236,14 @@ class Order(models.Model):
                 description=description)
 
 class OrderRecord(models.Model):
+    """
+    Order records store billing informations for products: the actual product
+    might be mutated and/or moved to another order but we do not want to loose
+    the details of old orders.
+
+    Used as source of trust to dynamically generate bill entries.
+    """
+
     order = models.ForeignKey(Order, on_delete=models.CASCADE)
     one_time_price = models.DecimalField(default=0.0,
             max_digits=AMOUNT_MAX_DIGITS,