feat: Better describe the circumstances under which run usage infor is included in API responses

Author: janbuchar

apify-api/openapi/components/schemas/actor-runs/Run.yaml

@@ -98,7 +98,16 @@ properties:
   usageTotalUsd:
     type: number
     nullable: true
+    description: >-
+      Total cost in USD for this run. Represents what you actually pay.
+      For run owners: includes platform usage (compute units) and/or event costs depending on the Actor's pricing model.
+      For non-owners: only available for Pay-Per-Event actors (event costs only).
+      Not available for Pay-Per-Result actors when you're not the Actor owner.
     example: 0.2654
   usageUsd:
     nullable: true
+    description: >-
+      Platform usage costs breakdown in USD. Only present if you own the run AND are paying for platform usage
+      (Pay-Per-Usage, Rental, or Pay-Per-Event with usage costs like standby Actors).
+      Not available for standard Pay-Per-Event actors or Pay-Per-Result actors owned by others.
     $ref: ./RunUsage.yaml